MAPSERVE 1.5 DOCUMENTATION
Here is an example of MapServe in action:
Clicking on the above image should launch MapServe, and retrieve a page telling you what you clicked on or near. (Note: You must view this page by retrieving it from a MacHTTP or WebSTAR server for MapServe to receive the AppleEvent information it needs to work. MapServe only works when used through MacHTTP or WebSTAR.)
Simply place the MapServe.acgi application somewhere within the folder that holds your server program. It doesn't have to be in the exact same folder as WebSTAR, but it must be in a folder the WebSTAR folder contains. It's a good idea to set up a naming scheme for your folders within your server's folder, because anyone who visits your server will get to see those names. It will help them if your file names make sense. For example, you might make a folder called "Tools" or "CGI" that can hold all your external applications for the server, or you can just use the supplied "MapServe" folder. Keep all the other files and folders with the MapServe application untill you don't need them anymore.
You should have already read through the documentation that comes with MacHTTP/WebSTAR, including the technical reference sections about calling external applications. If you haven't, take time to do so. You should also be familiar with HTML, making hypertext references ( <a href="URL"> ), and URLs and how they are specified in HTML documents.
The preferance box looks like this:
The second part of the preferences box you can leave at the default value, or you can change it to use a custom server name. If you want to customize it, you can type it in the text box. This is usefull if you want the program to give the user's browser a different server name other than the one WebSTAR knows. For example, if you have the DNS option of WebSTAR turned off, then WebSTAR sends it's name as an IP address (123.456.789.123). MapServe will then send URL's back to the browser in the form of http://123.456.789.123/blah.html. If you want it to send back the real server name, you can put this in the Preferences and it will send that in place of what WebSTAR tells it to send. (i.e. http://www.blah.com/).
Note: If you do use this option, MapServe doesn't send back any port number unless you specify it in the Prefences. (i.e. www.blah.com:8000)
This should bring up a graphic with several different colored shapes. Try clicking on one of the shapes. This should cause MapServe to start up on your server, and a file showing what you clicked on should be loaded up. If it fails for some reason, consult the section on troubleshooting later in this documentation.
Once you have a graphic file, you need to make an HTML document that uses it as an inline graphic. You can read about this in most HTML documentation. To give you a quick example, say you have a folder on your server called "Graphics" and a GIF file called "MyMap.gif" inside it. You would link to that graphic using HTML like this:
<img src="graphics/mymap.gif" ISMAP>.
The ISMAP part tells the client's browser program that the graphic is a map and it needs to send the coordinates of where the user clicked to the server.
Next you must make the graphic clickable, and specify MapServe as the program to link to when the graphic is clicked. You can do this in one of two ways, depending on what type of server you are using. If you are not using the commercial version of WebSTAR you only need to read the first of the two following sections: Using MapServe with MacHTTP or WebSTAR PS. If you are using the commercial version of WebSTARR you need to read both of the next two sections, Using MapServe with MacHTTP or WebSTAR PS and Special Features for use with WebSTAR Commercial Servers. If you're using MacHTTP or WebSTAR PS, skip the section on using MapServe with the full version of WebSTAR.
Here's an example:
<a href="path/to/mapserve.cgi$mapfilepath"> </a>
The mapfilepath is either a local, or a complete path to a file that
specifies the information that defines the different "hotspots" in the
graphic. See the Map File Format section below
to learn how to define these files.
A local path would be relative to the location of the MapServe.acgi application. For example, if you have a folder name "mapfiles" in the same folder as MapServe.acgi, you can use "mapfiles/mygraphic.map" as the mapfilepath part of the URL. Or if your files are in the same folder as MapServe.acgi, you can simply use "mygraphic.map" as your path.
A complete path would begin at the beginning of your server's directory structure. This would be something like "/folder1/folder2/mygraphic.map", where you have a folder named "folder1" in the same folder as WebSTAR or MacHTTP, then there is a "folder2" inside that, and the map file you are using is called "mygraphic.map" and is inside folder2.
So the complete HTML hyperlink reference to your clickable graphic named mygraphic.gif would be:
<a href="/path/to/mapserve.cgi$mygraphic.map"><img
src="mygraphic.gif" ismap></a>
To set this up, choose "Actions" from the Configure menu in the WebSTAR Admin application. There are two parts you need to fill in, the Application, and the Action Name.
In the Application box, specify the path to the MapServe application on your server, starting with a colon (:). For example, if MapServe is in a folder called CGI in your WebSTAR folder, you'll put :cgi:mapserve.acgi in the Application part.
For the Action Name, I suggest "MAP", although you can use anything you want.
Click the Add button and then Update to close the Action dialog box. Now you need to add a suffix mapping. Open the Suffix Mapping dialog box by chossing Suffix Mappings from the Configure menu in WebSTAR Admin.
Choose the Action type that you just defined from the Action pop-up menu, then put ".MAP" in the File Suffix box. The File Type should be "TEXT" and the Creator should be "*". Put "text/html" in the MIME type field, then hit the Add button and then the Update button. Now you've made a user defined action that will tell MapServe to process the request any time a file that ends in .map is accessed.
What this allows you to do, is simply use the name of the file in the <a href> tag instead of referencing the MapServe.acgi application and then giving the path to the .map file. An example follows:
<a href="mygraphic.map"><img src="mygraphic.gif" ISMAP></a>
In this example, the .map file and the .gif graphic are in the same directory as the .html file that refers to them both. When WebSTAR receives the request for the .map file, it sees that it is supposed to use the MAP action, which makes it launch MapServe.acgi and sends it the proper AppleEvent with the path to the .map file.
To use this feature, make sure you have set the Preferences correctly.
See the WebSTAR technical reference for more info on specifying an Action.
Notes: For MacHTTP/WebSTAR, case doesn't usually matter. Other types of servers, especially UNIX, may be case sensitive. I'm usually a lazy typist when writing HTML, so I generally don't capitalize anything. (Sidenote: Actually, some browsers are case-sensitive in certain instances. For example, forms making use of the POST method don't work on some versions of NCSA Mosaic for X-Windows unless POST is capitalized, so if anyone complains that they can't get an ISMAP graphic on your server to work, check to see if the capitalization may be a cause of the problem.)
If you don't want to use WebMap to make your map files, or you want the added features available in MapServe that WebMap doesn't support, then you need to know the format of the map file.
Note: A .map file editor is planned for the near future. Watch the MapServe home page for updates.
The map file is a plain text document that can be made with TeachText (or SimpleText) and many other text editors. For large graphics, you could even use a database program that can export it's data as tab or space separated text, though you're much better off just editing the text file yourself. (Also, very large, complex graphics with lots of objects defined will take longer to decode.)
The general form of each line is:
shape URL coordinatesHere is an example of a line that specifies a circle with it's center located at 13,12 and an edgepoint at 45,34:
circle http://your.server/folder/file.gif 13,12 45,34
Each line can be made up of any one of the following shapes or directives:
# this is a comment
default URL point URL coordinates
If the URL doesn't start with a slash, then it is treated as being local to the .map file (unless it contains a colon (:) character, in which case it is treated as a full URL). Local URL's in the .map file are pretty much the same as anything you can put into an <a href> tag. This means you can also use the "../" parent directory notation in a local URL.
If a file is local, MapServe appends "http://your.server.address:port" and any path information it needs to the front of what you specify as the local URL in the map file. If the port number is 80, then no port number is included in the URL. Also, you can override the servername and port number in the preferences box.
Since the fields in the map file are separated by whitespace (tabs or spaces), you cannot have any whitespace in your URL's (It's not a good idea to have any whitespace in any filenames on your web server). If you do happen to need to specify a URL for a file that has whitespace or funny characters in it's name, then you must encode that with the %xx encodings as specified in the MacHTTP/WebSTAR documentation, and several other documents specifying the use of URLs.
# # Order of entries does not matter, although the map will run faster if you # put more frequently used objects at the top. Also, a little speed will # be gained by placing the objects in the following order: Default, Rectangle, # Circles, Ovals, Polygons, Points. # default URL -- MapServe example default /mapserve/ # Blue rectangle rect /mapserve/mapservetest/blue.html 4,5 71,39 # Green circle circle /mapserve/mapservetest/green.html 181,57 198,57 # Orange polygon poly /mapserve/mapservetest/orange.html 224,23 219,55 268,67 281,24 257,4 250,36 224,23 # Red oval oval /mapserve/mapservetest/red.html 99,2 167,46 # Point 1 point /mapserve/mapservetest/point1.html 7,73 # Point 2 point /mapserve/mapservetest/point2.html 105,76 # Point 3 point /mapserve/mapservetest/point3.html 312,69 # Point 4 point /mapserve/mapservetest/point4.html 348,16
MapServe is also usefull for demonstrations of the World Wide Web where you can't be connected to the Internet. Because MacHTTP/WebSTAR can be run on a Mac using only LocalTalk, you can run MapServe with it for portable demonstrations, speeches, etc.
Send your shareware fees to me at the following address:
Kelly Campbell
1800 Platt, Apt. 4
Manhattan KS 66502
Please make checks payable to Kelly Campbell
I can be reached by email at CamkSoft@aol.com.
Also, I love to hear feedback (and of course bug reports) on the program,
so let me know if you have any.